package com.smart.community.region.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.region.dto.ResidentHouseholdAddDTO;
import com.smart.community.region.entity.ResidentHousehold;
import com.smart.community.region.vo.PageResult;
import com.smart.community.region.vo.ResidentHouseholdVO;
import com.smart.community.region.vo.ResidentMobileHouseholdVO;
import com.smart.community.region.dto.ResidentHouseholdUpdateDTO;

import com.smart.community.region.dto.ResidentQueryDTO;
import java.util.List;

/**
 * 住户房户关联服务接口
 * 
 * @author Wu.Liang
 * @since 2025-07-28
 */
public interface IResidentHouseholdService extends IService<ResidentHousehold> {
    
    /**
     * 查询房户住户列表
     * @param householdId 房户ID
     * @param current 当前页
     * @param size 每页条数
     * @return 分页结果
     * @throws Exception 统一异常
     */
    PageResult<ResidentHouseholdVO> getResidentList(Long householdId, Integer current, Integer size) throws Exception;
    
    /**
     * 根据条件查询住户列表（支持数据权限控制）
     * @param queryDTO 查询条件DTO
     * @return 分页结果
     * @throws Exception 统一异常
     */
    IPage<ResidentHouseholdVO> getResidentListWithConditions(ResidentQueryDTO queryDTO) throws Exception;
    
    /**
     * 新增住户到房户
     * @param householdId 房户ID
     * @param addDTO 新增DTO
     * @return 关联ID
     * @throws Exception 统一异常
     */
    Long addResidentToHousehold(Long householdId, ResidentHouseholdAddDTO addDTO) throws Exception;
    
    /**
     * 移除住户从房户
     * @param householdId 房户ID
     * @param residentId 住户ID
     * @throws Exception 统一异常
     */
    void removeResidentFromHousehold(Long householdId, Long residentId) throws Exception;
    
    /**
     * 更新住户房户关联信息
     * @param id 关联ID
     * @param updateDTO 更新DTO
     * @throws Exception 统一异常
     */
    void updateResidentHousehold(Long id, ResidentHouseholdUpdateDTO updateDTO) throws Exception;
    
    /**
     * 查询住户的房户列表
     * @param residentId 住户ID
     * @param current 当前页
     * @param size 每页条数
     * @return 分页结果
     * @throws Exception 统一异常
     */
    PageResult<ResidentHouseholdVO> getHouseholdList(Long residentId, Integer current, Integer size) throws Exception;

    /**
     * 移动端：根据当前登录用户ID聚合查询其所有房户信息（包含详细地址与展示字段）
     * Controller不得承载业务流程，故封装到Service
     * @param userId 用户ID
     * @return 房户信息VO列表
     */
    List<ResidentMobileHouseholdVO> listMobileHouseholdsByUserId(Long userId) throws Exception;
    
    /**
     * 根据业主ID查询家庭成员列表
     * 根据业主ID查询数据权限服务，获取权限对象'DataScopeInfo'中的业主关联的房户ID列表
     * 根据房户ID列表查询'sc_resident_household'，"residentType"=1或2的都是，然后关联"sc_resident"取信息列表
     * @param ownerId 业主ID
     * @return 家庭成员列表
     * @throws Exception 统一异常
     */
    List<ResidentHouseholdVO> getFamilyMembersByOwnerId(Long ownerId) throws Exception;
    
    /**
     * 根据业主ID查询租客列表
     * 根据业主ID查询数据权限服务，获取权限对象'DataScopeInfo'中的业主关联的房户ID列表
     * 根据房户ID列表查询'sc_resident_household'，"residentType"=3或4的都是，然后关联"sc_resident"取信息列表
     * @param ownerId 业主ID
     * @return 租客列表
     * @throws Exception 统一异常
     */
    List<ResidentHouseholdVO> getTenantsByOwnerId(Long ownerId) throws Exception;
    
    /**
     * 根据用户ID查询家庭成员列表
     * 根据用户ID查询数据权限服务，获取权限对象'DataScopeInfo'中的用户关联的房户ID列表
     * 根据房户ID列表查询'sc_resident_household'，"residentType"=1或2的都是，然后关联"sc_resident"取信息列表
     * @param userId 用户ID
     * @return 家庭成员列表
     * @throws Exception 统一异常
     */
    List<ResidentHouseholdVO> getFamilyMembersByUserId(Long userId) throws Exception;
    
    /**
     * 根据用户ID查询租客列表
     * 根据用户ID查询数据权限服务，获取权限对象'DataScopeInfo'中的用户关联的房户ID列表
     * 根据房户ID列表查询'sc_resident_household'，"residentType"=3或4的都是，然后关联"sc_resident"取信息列表
     * @param userId 用户ID
     * @return 租客列表
     * @throws Exception 统一异常
     */
    List<ResidentHouseholdVO> getTenantsByUserId(Long userId) throws Exception;
} 